{
  LW Shelf -- LightWave Surface Shaders

  The shelf is a window where users can store and retrieve presets for
  your plug-in.

  The shelf API supplies functions that let you subscribe (connect),
  set the context (tell the shelf that your interface is the active one),
  open the shelf window, and add, load and save presets.

  Based on lwshelf.h which is:
  Copyright 1999, NewTek, Inc.
}

{
  Copyright 2012, Jameel Halabi

  This unit is part of the BlaiseWave wrapper,
  which is licensed under the BSD 2-Clause license (see licenses/license.txt).
}
unit LW_Shelf;

{$mode objfpc}{$H+}

interface

uses
  LW_Dialog  ,
  LW_Globsrv ,
  LW_Types   ,
  LW_Image   ,
  LW_IO      ;

const
  LWSHELFFUNCS_GLOBAL ='LWShelfFuncs';

  { Load and Save Options }
  SHLF_BIN = 1 shl 1 ; // Binary LWIO State
  SHLF_ASC = 1 shl 2 ; // Ascii LWIO State
  SHLF_SEP = 1 shl 3 ; // Client uses separate file

  { LoadOk Codes }
  // enum en_SHELF_LOADOK
  SHLC_NOWAY = 0 ;  // Do not load. Client told user reason
  SHLC_DFLT  = 1 ;  // Use default confirmation dialog.
  SHLC_FORCE = 2 ;  // Load. Do Not confirm with user.

type
  { Callback Prototypes:
    --------------------
    LWShelfLoadOkFunc - Asks the subscribed client if it is ready to accept
                        loading a preset.
    LWShelfLoadFunc - Called to have the client load settings
    LWShelfSaveFunc - Called during save to obtain client settings

        These load and save callbacks provide for loading and
        saving client settings using the LW Load and Save State (LWIO.H)
        OR as a separate data file.

        Use of the LWIO states is recommended.

        Which format is used depends on the subscription flags
        where SHLF_BIN or SHLF_ASC uses the corresponding LWIO
        load/save states and SHLF_SEP indicates the client will
        save data to a separate file in whatever manner best suits
        its needs. The filename argument to the Load/SaveFunc
        callbacks is the filename the client should use for this
        activity.

    API Description:
    ----------------
    subscribe      - Adds a client to the Preset Shelf and returns a client ID.
    unsubscribe    - Unsubscribes the client. Clients should, at a minimum,
                     do this when its instance is destroyed.
    open           - Opens the Preset Shelf window and sets focus to the client.
    close          - Closes the Shelf.
    setContext     - Grabs the focus of the Shelf. This differs from the Open
                     method by making the client the active client but this
                     does not open the Shelf window.
    addPreset      - Called by the client to add a preset settings
    addNamedPreset   file to the Presets Shelf. The 'img' is an
                     LWImageID to use as the preset's thumbnail. The
                     'parms' is a NULL terminated list of string
                     parameter tags which can be used to conditionally
                     load settings from the preset.
    (Independent Operations)
    load/save      - These load/save preset settings files to an
                     arbitrary location specified by 'filename'. As part
                     of the shelf API, the load and save methods reuse
                     the client subscription settings (like userdata,
                     callbacks, etc.). If 'prompt_user' is true and the
                     preset contains a parameter list, this will prompt
                     user for input.                                          }
  PLWShelfClt = Pointer ; // opaque handle to shelf client
  PPLWShelfParmList = PPChar ;

  TLWShelfLoadOkFunc = function
                       (       UserData    : Pointer      ) : Integer ;

  TLWShelfLoadFunc   = procedure
                       (       UserData    : Pointer          ;
                         const Load        : PLWLoadState     ;
                         const filename    : PChar            ;
                               Parms       : PPLWShelfParmList ) ;

  TLWShelfSaveFunc   = procedure
                       (       UserData    : Pointer         ;
                         const Save        : PLWSaveState    ;
                         const FileName    : PChar           ) ;

  PLWShelfFuncs = ^TLWShelfFuncs ;
  TLWShelfFuncs = record
    { Client subscriptions }
    Subscribe      : function
                     (       Name           ,
                             SubName  	    : Pchar              ;
    			     UserData 	    : Pointer      	 ;
    			     Flags    	    : Integer      	 ;
                             LoadOkCallback : TLWShelfLoadOkFunc ;
                             LoadCallback   : TLWShelfLoadFunc   ;
                             SaveCallback   : TLWShelfSaveFunc   ) : PLWShelfClt ;
    Unsubscribe    : procedure
                     (       CTL            : PLWShelfClt        ) ;
    { Shelf Operations }
    Open           : procedure
    		     (       CTL            : PLWShelfClt        ) ;
    IsOpen         : function
    		     (       CTL            : PLWShelfClt        ) : Integer     ;
    Close          : procedure
    		     (       CTL            : PLWShelfClt        ) ;
    SetContext     : procedure
    		     (       CTL            : PLWShelfClt        ) ;
    AddPreset      : function
    		     (       CTL  	    : PLWShelfClt 	 ;
                             Img            : PLWImage		 ;
                             Parms 	    : PPLWShelfParmList  ) : Integer     ;
    { Independent Load and Save }
    Load           : procedure
    		     (       CTL            : PLWShelfClt        ;
                             Filename	    : PChar		 ;
                             PromptUser     : Integer 		 ) ;
    Save           : procedure
                     (       CTL            : PLWShelfClt        ;
                             Filename       : PChar		 ;
                             Thumbimgid	    : PLWImage	         ;
                             Parms          : PPLWShelfParmList  ) ;
    AddNamedPreset : function
                     (       CTL 	    : PLWShelfClt 	 ;
                             Img	    : PLWImage		 ;
                             Parms          : PPLWShelfParmList  ;
                       const Name           : PChar 		 ;
                       const Comment 	    : PChar 		 ) : Integer     ;
  end;

implementation

end.

